Adapt the SLC-PEC tutorial from the QDC Challenges 2025 repo [1] into a
documentation tutorial, updated for the released Qiskit Runtime and
restructured to follow the standard tutorial template.

New files:
- docs/tutorials/pec-with-shaded-lightcones.ipynb
- public/docs/images/tutorials/pec-with-shaded-lightcones/ (3 background
  schematics + extracted cell outputs)

Registered in docs/tutorials/_toc.json and docs/tutorials/index.mdx under
"Error mitigation", excluded from notebook CI in
scripts/config/notebook-testing.toml (consistent with other tutorials), and
given an owner in qiskit_bot.yaml.

Important changes and updates from the original [1]:

- API: migrated off the `executor_preview` branch to the released
  qiskit-ibm-runtime 0.47.0. `Executor`, `QuantumProgram`, and
  `NoiseLearnerV3` are imported from the top-level package, and noise-learner
  options are passed as a plain dict instead of `NoiseLearnerV3Options`.
  (qiskit-addon-slc 0.1.0 is already the latest release, so its pin is kept.)

- Credentials: replaced the hardcoded `shared_service` (token + `instance`
  CRN) and the named `QiskitRuntimeService(name="qdc-2025")` with a plain
  `QiskitRuntimeService()` that reads saved credentials.

- Live execution: removed all saved-job loading (the `shared_service.job(...)`
  IDs and the `load_cached_*` branches). The noise learner and Executor now
  run live, and the noise-learning job is tagged `TUT_SLC`.

- Noise-learning depth: set the deepest NLv3 `layer_pair_depths` value to half
  the circuit's two-qubit-layer depth, so the total learned depth matches the
  depth of the circuit being mitigated (computed programmatically from the
  boxed circuit). This noticeably improves the learned model for mitigation.

- Dropped the cluster-resources demonstration: removed the committed
  `merged_bounds_cluster.pickle` load. `local_scales` and the execution now
  use the live laptop-computed `merged_bounds`, and the sampling-overhead plot
  compares full PEC against PEC+SLC only. Its hardcoded y-limits were removed
  so it autoscales to the run's values.

- Cleanup: removed the `logging.basicConfig` INFO logging (kept the
  multiprocessing `set_start_method`/`OMP_NUM_THREADS` setup that SLC needs),
  and stripped INFO-log and local-path stream outputs.

- Structure: reformatted to the tutorial template (title/description
  frontmatter, learning outcomes, prerequisites, adapted background with
  relative doc links and committed AVIF figures, requirements, setup, next
  steps). The small-scale simulator section is kept but explains why
  simulation is skipped (SLC mitigates learned hardware noise). Converted
  in-page anchor links to plain references.

This run was executed on ibm_boston. The PEC+SLC results are not as strong as
the original QDC run: full PEC has a very high sampling overhead
(gamma^2 ~ 1.8e4), and although PEC+SLC reduces this ~17x and far outperforms
plain PEC, it does not fully settle within the 10% bias band in the
randomizations shown. The commentary has been updated to reflect this, and the
figures will likely be regenerated on a rerun (for example, with more
randomizations) before final publication.

Rerun the tutorial on hardware and refresh the results commentary to
match the new data:

- Update executed outputs: full PEC sampling cost (gamma^2) 1.8e4 -> 8.7e4,
  PEC+SLC sampling cost 1.1e3 -> 4.2e3, plus minor shifts in shots-kept
  fractions for noise learning (0.86 -> 0.85) and post-selection (~25.7%
  -> ~26.7%).
- Revise the results discussion: SLC now reduces overhead ~20-fold (was
  ~17-fold), and PEC+SLC settles in the physical region near the exact
  value (previously it converged above 1, in the unphysical region).
- Fix a broken sentence in the "Box the circuit" section ("the SLC
  workflow the use of" -> "the SLC workflow requires the use of").

Switch the hardware example from ibm_boston to ibm_fez and refresh all
cell outputs and the results commentary to match the new run (unmitigated
~0.2, full PEC gamma^2 ~4.2e3, PEC+SLC gamma^2 ~5.9e2 at ~10% residual
bias, ~7-fold overhead reduction).

Make the noise-learning depth schedule robust: keep a fixed candidate
schedule [1, 2, 4, 8, 12, 16, 24, 32, 40, 48], drop any candidate that
exceeds the circuit's depth, and always cap the deepest value at
max_layer_pair_depth so we never learn deeper than the circuit being
mitigated. Previously sorted({1, 2, 4, 8, 12, 16, max_layer_pair_depth})
could include hardcoded depths (e.g. 12, 16) beyond the circuit when
max_layer_pair_depth was small.

On counting two-qubit layers: we count InjectNoise-annotated boxes rather
than QuantumCircuit.depth(num_qubits == 2). After boxing, circuit data are
full-width BoxOp instructions, so a num_qubits == 2 filter matches nothing;
the boxing pass tags exactly one InjectNoise annotation per two-qubit layer,
so counting those boxes gives precisely the layer depth NLv3 will learn.
Added an inline comment to this effect.

Measure the two-qubit-layer depth with isa_circuit.depth(num_qubits == 2)
instead of counting InjectNoise-annotated boxes, and drop the now-unused
get_annotation / InjectNoise imports. After boxing, two-qubit gates are hidden
inside full-width BoxOp instructions, so a num_qubits == 2 filter on
boxed_circuit matches nothing and QuantumCircuit.depth does not recurse into
boxes; the pre-boxed ISA circuit gives the true 2q critical-path depth, halved
for layer pairs. Value unchanged for this circuit (depth_2q = 40 -> 20).

Refresh outputs from a new ibm_fez run and update the results commentary to
match (full PEC gamma^2 ~2.4e3, PEC+SLC gamma^2 ~3.7e2, ~6-fold reduction,
SLC settling near 0.9 within the ~10% residual-bias bound).

Co-authored-by: abbycross <across@us.ibm.com>

Co-authored-by: abbycross <across@us.ibm.com>

Co-authored-by: abbycross <across@us.ibm.com>

Co-authored-by: abbycross <across@us.ibm.com>

Co-authored-by: abbycross <across@us.ibm.com>

Co-authored-by: abbycross <across@us.ibm.com>